home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / util / libs / ReqToolsLib.lha / ReqToolsLib / Source / reqtools / rtezrequesta.c < prev    next >
Encoding:
C/C++ Source or Header  |  2001-07-02  |  13.2 KB  |  332 lines
  1.  
  2. /*
  3.     (C) 1999 - 2000 AROS - The Amiga Research OS
  4.     $Id: rtezrequesta.c,v 1.3 2000/11/26 16:53:48 stegerg Exp $
  5.  
  6.     Desc:
  7.     Lang: English
  8. */
  9.  
  10. #include <exec/types.h>
  11. #include <proto/exec.h>
  12. #include <proto/reqtools.h>
  13. #include <proto/intuition.h>
  14. #include <exec/libraries.h>
  15. #include <exec/memory.h>
  16. #include <libraries/reqtools.h>
  17. #include <aros/libcall.h>
  18.  
  19. #include "reqtools_intern.h"
  20. #include "general.h"
  21.  
  22. /*****************************************************************************
  23.  
  24.     NAME */
  25.  
  26.     AROS_LH5(ULONG, rtEZRequestA,
  27.  
  28. /*  SYNOPSIS */
  29.  
  30.     AROS_LHA(char *, bodyfmt, A1),
  31.     AROS_LHA(char *, gadfmt, A2),
  32.     AROS_LHA(struct rtReqInfo *, reqinfo, A3),
  33.     AROS_LHA(APTR, argarray, A4),
  34.     AROS_LHA(struct TagItem *, taglist, A0),
  35.  
  36. /*  LOCATION */
  37.  
  38.     struct ReqToolsBase *, ReqToolsBase, 11, ReqTools)
  39.  
  40. /*  FUNCTION
  41.     This function puts up a requester for you and waits for a response
  42.     from the user. If the response is positive, this procedure returns
  43.     TRUE. If the response is negative, this procedure returns FALSE.
  44.     The function may also return an IDCMP flag or a value corresponding
  45.     with one of other possible responses (see below).
  46.  
  47.     'gadfmt' may contain several possible responses. Separate these
  48.     responses by a '|'. For example: "Yes|No", or 'Yes|Maybe|No". The
  49.     responses should be typed in the same order as they will appear on
  50.     screen, from left to right. There is no limit to the number of
  51.     responses other than the width of the screen the requester will
  52.     appear on.
  53.  
  54.     'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a
  55.     new line to be started (surprise, surprise :-).
  56.     You may also include printf() style formatting codes. The format
  57.     arguments should be pointed to by 'argarray'.
  58.     You can use formatting codes in 'gadfmt' as well. The arguments for
  59.     this format string should follow the ones for 'bodyfmt'.
  60.  
  61.     NOTE: The formatting is done by exec.library/RawDoFmt(), so be
  62.         aware that to display a 32-bit integer argument you must use
  63.         "%ld", not "%d", since RawDoFmt() is "word-oriented."
  64.  
  65.     The second and third function use a variable number of arguments.
  66.     These functions can be found in 'reqtools[nb].lib'.
  67.     The second function has the RawDoFmt() arguments as variable args,
  68.     the third the tags. If you need both this is what you can do:
  69.  
  70.     ...
  71.     {
  72.        ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
  73.  
  74.        rtEZRequest ("String, num: %s, %ld", "Ok", NULL,
  75.                                        (struct TagItem *)tags, "six", 6);
  76.     }
  77.     ...
  78.  
  79.     You can satisfy the requester with the following keyboard shortcuts:
  80.         'Y' or Left Amiga 'V' for a positive response,
  81.         ESC, 'N', 'R' or Left Amiga 'B' for a negative response.
  82.  
  83.     If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the
  84.     RETURN key is also accepted as a shortcut for the positive response
  85.     (can be changed using RTEZ_DefaultResponse, see below). The
  86.     response that will be selected when you press RETURN will be
  87.     printed in bold.
  88.  
  89.     The EZREQF_LAMIGAQUAL flag should be used when you put up a
  90.     requester for a destructive action (e.g. to delete something). When
  91.     it is set the keyboard shortcuts are limited to Left Amiga 'V' and
  92.     'B' so it is harder to accidently select something you will regret.
  93.     Note that the RETURN and ESC key remain active!  To disable the
  94.     RETURN key use the EZREQF_NORETURNKEY flag. The ESC key cannot be
  95.     disabled.
  96.  
  97.     You may pass a NULL for 'gadfmt', but make sure you know what you
  98.     are doing. Passing a NULL opens an EZRequester with NO responses,
  99.     just a body text. This implies the user has no means of "answering"
  100.     this requester. You must therefore use the RT_IDCMPFlags tag to
  101.     allow some other events to end the requester (e.g.
  102.     IDCMP_MOUSEBUTTONS, IDCMP_INACTIVEWINDOW,...) or you must make use
  103.     of the ReqHandler feature. Using a requester handler you can end
  104.     the requester by program control. This way you can e.g. put up a
  105.     requester before you start loading a file and remove it after the
  106.     file has been loaded. Do not pass an empty string as 'gadfmt'!
  107.  
  108.     'reqinfo' can be used to customize the requester. For greater
  109.     control use the tags listed below. The advantage of the rtReqInfo
  110.     structure is that it is global, where tags have to be specified
  111.     each function call. See libraries/reqtools.[hi] for a description
  112.     of the rtReqInfo structure.
  113.    
  114.     INPUTS
  115.     bodyfmt  - requester body text, can be format string a la RawDoFmt().
  116.     gadfmt   - text for gadgets (left to right, separated by '|') or NULL.
  117.     argarray - pointer to array of arguments for format string(s).
  118.     reqinfo  - pointer to a rtReqInfo structure allocated with
  119.         rtAllocRequest() or NULL.
  120.     taglist  - pointer to a TagItem array.
  121.  
  122.     TAGS
  123.     RT_Window - (struct Window *) Window that will be used to find the
  124.         screen to put the requester on. You *MUST* supply this if you
  125.         are a task calling this function and not a process! This is
  126.         because tasks don't have a pr_WindowPtr.
  127.  
  128.     RT_IDCMPFlags - (ULONG) Extra idcmp flags to return on. If one
  129.         these IDCMP flags causes the requester to abort the return code
  130.         will equal the flag in question.
  131.  
  132.     RT_ReqPos - (ULONG) One of the following:
  133.  
  134.         REQPOS_POINTER - requester appears where the mouse pointer is
  135.             (default).
  136.  
  137.         REQPOS_CENTERSCR - requester is centered on the screen.
  138.  
  139.         REQPOS_CENTERWIN - requester is centered in the window (only
  140.             works if the pr_WindowPtr of your process is valid or if you
  141.             use RT_Window). If RT_Window is NULL the requester will be
  142.             centered on the screen.
  143.  
  144.         REQPOS_TOPLEFTSCR - requester appears at the top left of the
  145.             screen.
  146.  
  147.         REQPOS_TOPLEFTWIN - requester appears at the top left of the
  148.             window (only works if the pr_WindowPtr of your process is
  149.             valid or if you use RT_Window).
  150.         
  151.         The requester will always remain in the visible part of the
  152.         screen, so if you use the Workbench 2.0 ScreenMode preferences
  153.         editor to enlarge your Workbench screen and you scroll around,
  154.         the requester will always appear in the part you can see.
  155.         REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the
  156.         visible part of the screen. So if you use one of these the
  157.         requester will be appear in the center or the top left off what
  158.         you can see of the screen as opposed to the entire screen.
  159.         
  160.         REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
  161.         REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there
  162.         is no parent window. So you can safely use these without
  163.         worrying about the existence of a window.
  164.  
  165.     RT_LeftOffset - (ULONG) Offset of left edge of requester relative to
  166.         position specified with RT_ReqPos (does not offset the
  167.         requester when RT_ReqPos is REQPOS_POINTER).
  168.  
  169.     RT_TopOffset - (ULONG) Offset of top edge of requester relative to
  170.         position specified with RT_ReqPos (does not offset the
  171.         requester when RT_ReqPos is REQPOS_POINTER).
  172.  
  173.     RT_PubScrName - (char *) Name of public screen requester should
  174.         appear on. When this tag is used the RT_Window tag will be
  175.         ignored. If the public screen is not found the requester will
  176.         open on the default public screen.
  177.         
  178.         Only works on Kickstart 2.0! reqtools.library does not check
  179.         this, it is up to you *NOT* to use this tag on Kickstart 1.3 or
  180.         below! Note that the 1.3 version of reqtools.library also
  181.         understands and supports this tag (on 2.0).
  182.  
  183.     RT_Screen - (struct Screen *) Address of screen to put requester
  184.         on. You should never use this, use RT_Window or RT_PubScrName.
  185.  
  186.     RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can
  187.         start an "asynchronous" requester. ti_TagData of the tag must
  188.         hold the address of a pointer variable to a rtHandlerInfo
  189.         structure. The requester will initialize this pointer and will
  190.         return immediately after its normal initialization. The return
  191.         code will not be what you would normally expect. If the return
  192.         code is _not_ equal to CALL_HANDLER an error occurred and you
  193.         should take appropriate steps.
  194.         
  195.         If the return code was CALL_HANDLER everything went ok and the
  196.         requester will still be up! See the explanation for
  197.         rtReqHandlerA() below for the following steps you have to take.
  198.  
  199.     RT_WaitPointer - (BOOL) If this is TRUE the window calling the
  200.         requester will get a standard wait pointer set while the
  201.         requester is up. This will happen if you used the RT_Window tag
  202.         or if your process's pr_WindowPtr is valid. Note that after the
  203.         requester has finished your window will be ClearPointer()-ed.
  204.         
  205.         If you used a custom pointer in your window you will have to
  206.         re-set it, or not use the RT_WaitPointer tag and put up a wait
  207.         pointer yourself. If your program requires ReqTools V38 it is
  208.         advised you use RT_LockWindow instead. Defaults to FALSE.
  209.  
  210.     RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the
  211.         requester will get locked. It will no longer accept any user
  212.         input and it will get standard wait pointer set. This will
  213.         happen only if you used the RT_Window tag or if your process's
  214.         pr_WindowPtr is valid. RT_LockWindow will restore a custom
  215.         pointer if you have used one (unlike RT_WaitPointer). So you do
  216.         not have to worry about having to restore it yourself. It is
  217.         advised you use this tag as much as possible. Defaults to FALSE.
  218.  
  219.         Under Kickstart V39 the original window pointer will not be
  220.         restored if it was set using SetWindowPointer(). You will have
  221.         to restore the pointer yourself in this case.
  222.  
  223.     RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop
  224.         the screen the requester will appear on to the front. Default is
  225.         TRUE.
  226.  
  227.     RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share
  228.         the IDCMP port of the parent window. Use this tag together with
  229.         the RT_Window tag to indicate the window to share IDCMP with.
  230.         Sharing the IDCMP port produces less overhead, so it is advised
  231.         you use this tag. Defaults to FALSE.
  232.  
  233.     RT_Locale - (struct Locale *) [V38] Locale to determine what
  234.         language to use for the requester text. If this tag is not used
  235.         or its data is NULL, the system's current default locale will
  236.         be used. Default NULL.
  237.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  238.         this hook for each IDCMP message it gets that doesn't belong to
  239.         its window. Only applies if you used the RT_ShareIDCMP tag to
  240.         share the IDCMP port with the parent window. Parameters are as
  241.         follows:
  242.         
  243.             A0 - (struct Hook *) your hook
  244.             A2 - (struct rtReqInfo *) your requester info
  245.             A1 - (struct IntuiMessage *) the message
  246.         
  247.         After you have finished examining the message and your hook
  248.         returns, ReqTools will reply the message. So do not reply the
  249.         message yourself!
  250.  
  251.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  252.         character in the gadget label to be underscored. This is to
  253.         define a keyboard shortcut for this gadget. Example: to define
  254.         the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh,
  255.         No!" you would use the tag RT_Underscore, '_' and pass as
  256.         gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is
  257.         used for string formatting. The usual character to use is '_'
  258.         like in the example.
  259.         
  260.         IMPORTANT: the shortcuts defined using RT_Underscore take
  261.             precedence of the default shortcuts! It is for example not
  262.             wise to use a 'N' for a positive response! Pick your
  263.             shortcuts carefully!
  264.  
  265.     RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
  266.         requester. Default is to use the screen font. Note that the
  267.         font must already be opened by you. ReqTools will call
  268.         OpenFont() on this TextAttr, _not_ OpenDiskFont()!  If the font
  269.         cannot be opened using OpenFont() the default screen font will
  270.         be used.
  271.  
  272.     RTEZ_ReqTitle - (char *) Title of requester window, default is
  273.         "Request" unless the requester has less than 2 responses, then
  274.         the default title is "Information".
  275.  
  276.     RTEZ_Flags - (ULONG) Flags for rtEZRequestA():
  277.  
  278.         EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for
  279.             positive response.
  280.  
  281.         EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left
  282.             Amiga 'V' and 'B', ESC and RETURN.
  283.  
  284.         EZREQF_CENTERTEXT - centers each line of body text in the
  285.             requester window. Useful for about requesters.
  286.  
  287.     RTEZ_DefaultResponse - (ULONG) Response value that will be returned
  288.         when the user presses the return key. Will be ignored if the
  289.         EZREQF_NORETURNKEY flag is set. The text for this response will
  290.         be printed in bold. Default is 1.
  291.  
  292.     RESULT
  293.     ret - 1 (TRUE) for leftmost (positive) response, then each
  294.         consecutive response will return 1 more, the rightmost (false)
  295.         response will return 0 (FALSE), so 1,2,3,...,num-1,0 -- or
  296.         idcmp flag.
  297.  
  298.     NOTES
  299.     Automatically adjusts the requester to the screen font.
  300.  
  301.     rtEZRequestA() checks the pr_WindowPtr of your process to find the
  302.     screen to put the requester on.
  303.  
  304.     EXAMPLE
  305.  
  306.     BUGS
  307.     none known
  308.  
  309.     SEE ALSO
  310.     exec.library/RawDoFmt(), rtReqHandlerA()
  311.  
  312.     INTERNALS
  313.  
  314.     HISTORY
  315.  
  316. ******************************************************************************/
  317. {
  318.     AROS_LIBFUNC_INIT
  319.  
  320.     return GetString(bodyfmt,
  321.                  (LONG)argarray,
  322.              gadfmt,
  323.              0,
  324.              NULL,
  325.              IS_EZREQUEST,
  326.              reqinfo,
  327.              taglist);
  328.              
  329.     AROS_LIBFUNC_EXIT
  330.  
  331. } /* rtEZRequestA */
  332.